package com.apikey.auth.service;

import com.apikey.auth.entity.ApiKey;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * API Key管理服务接口
 * 提供API Key的核心业务逻辑
 *
 * @author API Key Framework
 * @version 1.0
 */
public interface ApiKeyService {

    /**
     * 创建新的API Key
     *
     * @param name         API Key名称
     * @param permissions  权限列表（逗号分隔）
     * @param userId       用户ID
     * @param operatorId   操作者ID
     * @param description  描述
     * @param dailyLimit   每日限制
     * @param monthlyLimit 每月限制
     * @param expiresAt    过期时间
     * @return 创建的API Key
     */
    ApiKey createApiKey(String name, String permissions, String userId, String operatorId,
                        String description, Integer dailyLimit, Integer monthlyLimit, LocalDateTime expiresAt);

    /**
     * 根据ID查找API Key
     *
     * @param id API Key ID
     * @return API Key实体
     */
    Optional<ApiKey> findById(Long id);

    /**
     * 根据API Key值查找API Key
     *
     * @param keyValue API Key值
     * @return API Key实体
     */
    Optional<ApiKey> findByKeyValue(String keyValue);

    /**
     * 分页查询API Key
     *
     * @param pageable 分页参数
     * @return API Key分页结果
     */
    Page<ApiKey> findAll(Pageable pageable);

    /**
     * 根据用户ID分页查询API Key
     *
     * @param userId   用户ID
     * @param pageable 分页参数
     * @return API Key分页结果
     */
    Page<ApiKey> findByUserId(String userId, Pageable pageable);

    /**
     * 根据状态分页查询API Key
     *
     * @param status   状态
     * @param pageable 分页参数
     * @return API Key分页结果
     */
    Page<ApiKey> findByStatus(String status, Pageable pageable);

    /**
     * 根据名称模糊查询API Key
     *
     * @param name     名称关键字
     * @param pageable 分页参数
     * @return API Key分页结果
     */
    Page<ApiKey> findByNameContaining(String name, Pageable pageable);

    /**
     * 更新API Key
     *
     * @param id           API Key ID
     * @param name         新名称
     * @param permissions  新权限
     * @param operatorId   操作者ID
     * @param description  新描述
     * @param dailyLimit   新每日限制
     * @param monthlyLimit 新每月限制
     * @param expiresAt    新过期时间
     * @return 更新后的API Key
     */
    ApiKey updateApiKey(Long id, String name, String permissions, String operatorId,
                        String description, Integer dailyLimit, Integer monthlyLimit, LocalDateTime expiresAt);

    /**
     * 切换API Key状态
     *
     * @param id         API Key ID
     * @param operatorId 操作者ID
     * @return 更新后的API Key
     */
    ApiKey toggleStatus(Long id, String operatorId);

    /**
     * 激活API Key
     *
     * @param id         API Key ID
     * @param operatorId 操作者ID
     * @return 更新后的API Key
     */
    ApiKey activate(Long id, String operatorId);

    /**
     * 停用API Key
     *
     * @param id         API Key ID
     * @param operatorId 操作者ID
     * @return 更新后的API Key
     */
    ApiKey deactivate(Long id, String operatorId);

    /**
     * 续期API Key
     *
     * @param id            API Key ID
     * @param newExpiryTime 新过期时间
     * @param operatorId    操作者ID
     * @return 更新后的API Key
     */
    ApiKey renewApiKey(Long id, LocalDateTime newExpiryTime, String operatorId);

    /**
     * 软删除API Key
     *
     * @param id         API Key ID
     * @param operatorId 操作者ID
     * @return 是否删除成功
     */
    boolean deleteApiKey(Long id, String operatorId);

    /**
     * 验证API Key是否有效
     *
     * @param keyValue API Key值
     * @return 是否有效
     */
    boolean validateApiKey(String keyValue);

    /**
     * 验证API Key是否有指定权限
     *
     * @param keyValue   API Key值
     * @param permission 权限
     * @return 是否有权限
     */
    boolean hasPermission(String keyValue, String permission);

    /**
     * 增加API Key使用次数
     *
     * @param keyValue API Key值
     * @return 是否增加成功
     */
    boolean incrementUsage(String keyValue);

    /**
     * 重置API Key使用统计
     *
     * @param keyValue     API Key值
     * @param resetDaily   是否重置每日统计
     * @param resetMonthly 是否重置每月统计
     * @return 是否重置成功
     */
    boolean resetUsage(String keyValue, boolean resetDaily, boolean resetMonthly);

    /**
     * 生成新的API Key值
     *
     * @return 新的API Key值
     */
    String generateApiKeyValue();

    /**
     * 检查API Key名称是否已存在
     *
     * @param name API Key名称
     * @return 是否已存在
     */
    boolean existsByName(String name);

    /**
     * 检查API Key值是否已存在
     *
     * @param keyValue API Key值
     * @return 是否已存在
     */
    boolean existsByKeyValue(String keyValue);

    /**
     * 获取API Key统计信息
     *
     * @return 统计信息Map
     */
    Map<String, Object> getStatistics();

    /**
     * 获取用户的API Key统计
     *
     * @param userId 用户ID
     * @return 用户统计信息
     */
    Map<String, Object> getUserStatistics(String userId);

    /**
     * 获取状态分布统计
     *
     * @return 状态分布Map
     */
    Map<String, Long> getStatusDistribution();

    /**
     * 获取每日创建统计
     *
     * @param days 统计天数
     * @return 每日创建统计列表
     */
    List<Map<String, Object>> getDailyCreationStats(int days);

    /**
     * 查找即将过期的API Key
     *
     * @param days 提前天数
     * @return 即将过期的API Key列表
     */
    List<ApiKey> findExpiringApiKeys(int days);

    /**
     * 查找已过期的API Key
     *
     * @return 已过期的API Key列表
     */
    List<ApiKey> findExpiredApiKeys();

    /**
     * 查找使用量超限的API Key
     *
     * @return 使用量超限的API Key列表
     */
    List<ApiKey> findOverLimitApiKeys();

    /**
     * 自动处理过期的API Key
     *
     * @return 处理的API Key数量
     */
    int handleExpiredApiKeys();

    /**
     * 批量更新API Key状态
     *
     * @param ids        API Key ID列表
     * @param status     新状态
     * @param operatorId 操作者ID
     * @return 更新的数量
     */
    int batchUpdateStatus(List<Long> ids, String status, String operatorId);

    /**
     * 批量删除API Key
     *
     * @param ids        API Key ID列表
     * @param operatorId 操作者ID
     * @return 删除的数量
     */
    int batchDelete(List<Long> ids, String operatorId);

    /**
     * 导出API Key数据
     *
     * @param userId 用户ID（可选）
     * @param status 状态（可选）
     * @return CSV格式的数据
     */
    String exportApiKeys(String userId, String status);

    /**
     * 清理已删除的API Key数据
     *
     * @param retentionDays 保留天数
     * @return 清理的数量
     */
    int cleanupDeletedApiKeys(int retentionDays);

    /**
     * 多条件分页查询API Key
     *
     * @param userId     用户ID过滤
     * @param status     状态过滤
     * @param permission 权限过滤
     * @param pageable   分页参数
     * @return API Key分页结果
     */
    Page<ApiKey> findApiKeys(String userId, String status, String permission, Pageable pageable);

    /**
     * 更新API Key
     *
     * @param id           API Key ID
     * @param name         名称
     * @param description  描述
     * @param permissions  权限
     * @param expiryTime   过期时间
     * @param dailyLimit   每日限制
     * @param monthlyLimit 每月限制
     * @param operatorId   操作者ID
     * @return 更新后的API Key
     */
    ApiKey updateApiKey(Long id, String name, String description, String permissions,
                        LocalDateTime expiryTime, Integer dailyLimit, Integer monthlyLimit,
                        String operatorId);

    /**
     * 创建API Key（简化版本）
     *
     * @param apiKey API Key实体
     * @return 创建的API Key
     */
    ApiKey createApiKey(ApiKey apiKey);

    /**
     * 更新API Key（简化版本）
     *
     * @param apiKey API Key实体
     * @return 更新后的API Key
     */
    ApiKey updateApiKey(ApiKey apiKey);

    /**
     * 切换API Key状态（简化版本）
     *
     * @param id API Key ID
     * @return 更新后的API Key
     */
    ApiKey toggleStatus(Long id);

    /**
     * 续期API Key（简化版本）
     *
     * @param id   API Key ID
     * @param days 续期天数
     * @return 更新后的API Key
     */
    ApiKey renewApiKey(Long id, int days);

    /**
     * 删除API Key（简化版本）
     *
     * @param id API Key ID
     */
    void deleteApiKey(Long id);

    /**
     * 获取API Key总数
     *
     * @return 总数
     */
    long getTotalCount();

    /**
     * 获取活跃API Key数量
     *
     * @return 活跃数量
     */
    long getActiveCount();

    /**
     * 获取已过期API Key数量
     *
     * @return 过期数量
     */
    long getExpiredCount();

    /**
     * 获取已禁用API Key数量
     *
     * @return 禁用数量
     */
    long getDisabledCount();
}